jsonEncode

Type

function

Summary

Converts a value to a string in JSON format, with minimal whitespace.

Syntax

jsonEncode(<value>)

Description

Use the jsonEncode function to convert a value into a string in JSON format with minimal whitespace.

Converting values to JSON works for both non-array and array values. In the case of array values, the function acts recursively on each element of each array encountered.

The JSON resulting from conversion of a value depends on the kinds of values it encounters. As LiveCode generally makes no distinction between types of non- array values, the function uses their strict type.

If the value is strictly a nothing, then the value is output as JSON null.

If the value is strictly a boolean, then the value is output as JSON true or JSON false.

If the value is strictly a number, then the value is output as a JSON number, e.g. 0, -100, 100.3e-10.

If the value is strictly a string, then the value is output as a string. Any control (those with codepoint less than 32), quote or backslash characters are always escaped.

If the value is strictly a binary string, then the value is treated as a native encoded string, and output as a JSON string.

If the value is strictly a sequence, then the value is output as a JSON array. e.g. [1, 2, 3], [null, [], false, \"Hello\"].

If the value is strictly a dictionary, then the value is output as a JSON object. e.g. {\"a\": 1, \"b\": 2}, {\"1\": [], \"2\": \"Hello\", \"foo\": {}}.

If the JSON is being passed to other systems which have more strict rules about values and types, then it will often be necessary to ensure a value is output in the required JSON format. This can be done by using the as a operators before passing to jsonEncode.

For example, if a JSON number token is required for a particular value then use the as a number operator:

    put item 2 of \"100.0,100.1,100.2\" into tMyValue
    put jsonEncode(tMyValue) -- outputs `\"100.1\"`
    put \"100.1\" as a number into tMyValue
    put jsonEncode(tMyValue) -- outputs `100.1`

Here as tMyValue is being taken from an item of a string, it will remain a string (from the point of view of jsonEncode) and so must be explicitly converted to a number to ensure it is formatted as a JSON number.

Similarly, if a JSON object is required for a particular value, regardless of its keys, then use the as a dictionary operator:

    put \"Hello\" into tMyObject[1]
    put \"World\" into tMyObject[2]
    put jsonEncode(tMyObject) -- outputs `[\"Hello\",\"World\"]`
    put jsonEncode(tMyObject as a dictionary) -- outputs `{\"1\":\"Hello\",\"2\":\"World\"}`

Here as tMyObject is a sequence (and has not been marked otherwise), by default jsonEncode will format it as a JSON array. However, using the as a dictionary operator on the value will cause it to be formatted as a JSON object.

note

When arrays are output as JSON objects, the order of the keys is determined by internal hash order and thus is not guaranteed to be any particular order.

Parameters

Name	Type	Description
value		The value to be converted to JSON format.
options		If present, then specifies options controlling the generated JSON.

Examples

jsonEncode(nothing) -- returns "null"

jsonEncode(true) -- returns "true"

jsonEncode(1 + 1) -- returns "2"

jsonEncode("Hello" & return & "World") -- returns "Hello\nWorld" (quoted)

jsonEncode(numToCodepoint(0xE9)) -- returns "é" (quoted)

jsonEncode([]) -- returns "[]"

jsonEncode({}) -- returns "{}"

jsonEncode([null, false, [], {}]) -- returns "[null,false,[],{}]"

Related

function: jsonDecode

operator: is a, is strictly a, as a

Compatibility and Support

Introduced

LiveCode Create 1.0

OS

mac

windows

linux

ios

android

web

Platforms

desktop

server

mobile